Add directional wave features and release v1.1.0 by nickreich · Pull Request #15 · reichlab/idmodels

nickreich · 2025-11-17T02:54:31Z

Summary

This PR adds directional wave features to the GBQR model for capturing spatial-temporal patterns in disease spread, and releases version ~~0.2.0~~ 1.1.0 of the package.

Key Features

Directional Wave Features:

Distance-weighted spatial features in 8 directions (N, NE, E, SE, S, SW, W, NW)
Temporal lags for historical patterns (configurable, default: lag1, lag2)
Optional velocity features for rate of change
Aggregate feature for overall neighborhood influence
Fully backwards compatible (disabled by default)

Spatial Utilities:

New spatial_utils.py module with haversine distance and bearing calculations
Bundled state centroid data (state_centroids.csv) from US Census Bureau TIGER/Line Shapefiles
Efficient caching and neighbor precomputation
Extensible design for county/HSA levels in future

Configuration Example:

model_config.use_directional_waves = True
model_config.wave_directions = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW']
model_config.wave_temporal_lags = [1, 2]
model_config.wave_max_distance_km = 1000

Files Added

Core Implementation:

src/idmodels/spatial_utils.py - Spatial utilities with distance/bearing calculations
src/idmodels/data/state_centroids.csv - Geographic coordinates for 50 states + DC + PR
src/idmodels/data/README.md - Data source documentation

Tests:

tests/unit/test_spatial_utils.py - 20 unit tests for spatial utilities
tests/unit/test_directional_wave_features.py - 14 unit tests for feature generation
tests/integration/test_gbqr_wave_features.py - 7 integration tests for GBQR pipeline

Documentation:

docs/directional_wave_features.md - Comprehensive user guide with examples

Files Modified

src/idmodels/preprocess.py - Added create_directional_wave_features() function
src/idmodels/gbqr.py - Integrated wave features into preprocessing pipeline
pyproject.toml - Updated package data inclusion
src/idmodels/__init__.py - Bumped version to 0.2.0
CHANGELOG.md - Added v0.2.0 release notes

Data Source & Transparency

The state centroids are now bundled as a CSV file rather than hardcoded, providing:

Transparency: Clear documentation of data source (US Census Bureau)
Maintainability: Easy updates without touching code
Extensibility: Simple to add county, HSA, or other geographic levels
Auditability: Users can inspect coordinate values

Data Accuracy: ~10 meters (4 decimal places), suitable for state-level spatial analysis

Test Results

✅ 45 tests pass including all new directional wave feature tests

20 unit tests for spatial utilities
14 unit tests for feature generation
7 integration tests for GBQR pipeline
Full backwards compatibility verified

❌ 3 pre-existing failures in SARIX Fourier tests (unrelated to this PR)

Backwards Compatibility

✅ Fully backwards compatible

Wave features disabled by default (use_directional_waves = False)
Existing model configurations work without modification
Graceful handling of missing configuration attributes

Version

Bumped from 0.1.0 → ~~0.2.0~~ 1.1.0

Documentation

See docs/directional_wave_features.md for:

Detailed feature explanations
Configuration parameter reference
Usage examples and best practices
Technical implementation details
Troubleshooting guide

Quick Start

Enable with default settings:

model_config.use_directional_waves = True

Customize for 4 cardinal directions only:

model_config.use_directional_waves = True
model_config.wave_directions = ['N', 'S', 'E', 'W']

Future Enhancements

Potential extensions (not in this PR):

County and HSA-level coordinate support
Custom distance weighting functions
Population-weighted features
Temporal smoothing

🤖 Generated with Claude Code

Implement distance-weighted directional wave features to capture spatial patterns in disease spread across neighboring locations. Features compute weighted averages of neighbor incidence in 8 directions (N, NE, E, SE, S, SW, W, NW) with support for temporal lags and velocity calculations. New modules: - src/idmodels/spatial_utils.py: Geographic utilities for distance, bearing, and directional neighbor calculations using Haversine formula - src/idmodels/data/: US state centroids with geographic coordinates Feature integration: - src/idmodels/preprocess.py: create_directional_wave_features() function with inverse distance weighting and configurable parameters - src/idmodels/gbqr.py: Integrated wave features into GBQR preprocessing pipeline with backwards compatibility Configuration: - pyproject.toml: Added examples dependencies (jupyter, matplotlib, plotly), fixed setuptools package discovery, and configured package data inclusion Testing: - 20 unit tests for spatial utilities - 14 unit tests for feature generation - 7 integration tests for GBQR pipeline - All tests passing Key features: - Configurable directions, temporal lags, and distance thresholds - Optional velocity features (rate of change) - Aggregate spatial feature (overall neighbor average) - Handles missing neighbors gracefully (NaN for locations without neighbors) - Efficient neighbor caching to avoid redundant distance calculations - Updated multicollinearity warning to clarify that opposite directions provide independent information in directional spread scenarios Disabled by default for backwards compatibility. Enable with use_directional_waves = True in model configuration. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

This release adds directional wave features for spatial-temporal disease modeling and removes optional example dependencies to streamline the package. Changes: - Bump version from 0.1.0 to 0.2.0 - Remove optional "examples" dependencies (jupyter, matplotlib, plotly) - Update CHANGELOG.md with comprehensive 0.2.0 release notes - Regenerate uv.lock with updated dependencies 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Auto-fix 449 linting errors including: - Quote style standardization (single to double quotes) - Import statement sorting and formatting - Remove unused imports All checks now pass with ruff v0.14.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

… Also, modified pre-commit-config.

src/idmodels/__init__.py

matthewcornell

After a quick-ish scan, this looks good. Excited to see how models using this perform!

Documents the NSSP data source support added in PR #14, including: - NSSP data source support for SARIX and GBQR models - HSA and state-level forecasting - Breaking change: locations replaced by states/hsas config Also adds codespell config to ignore "HSA" acronym. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

lshandross

Had a couple of questions but unless any of them stand out as something to be addressed, I don't want to slow down the development process and getting this merged in

tests/integration/test_gbqr_wave_features.py

nickreich and others added 4 commits November 14, 2025 10:09

adding directional wave features documentation

b870a07

nickreich requested review from lshandross and matthewcornell December 8, 2025 15:15

nickreich changed the title ~~Add directional wave features and release v0.2.0~~ Add directional wave features and release v1.1.0 Dec 8, 2025

nickreich added 2 commits December 8, 2025 11:16

updating changelog and version to align with interim package updates.…

c491556

… Also, modified pre-commit-config.

Merge branch 'main' into ngr/add-spatial-covariates

bf10aa5

matthewcornell reviewed Dec 8, 2025

View reviewed changes

src/idmodels/__init__.py Show resolved Hide resolved

matthewcornell previously approved these changes Dec 8, 2025

View reviewed changes

nickreich dismissed matthewcornell’s stale review via 4ba0d10 December 8, 2025 18:10

matthewcornell approved these changes Dec 8, 2025

View reviewed changes

lshandross approved these changes Dec 8, 2025

View reviewed changes

tests/integration/test_gbqr_wave_features.py Show resolved Hide resolved

tests/integration/test_gbqr_wave_features.py Show resolved Hide resolved

nickreich mentioned this pull request Dec 9, 2025

add tests that check that a GBQR model fits with wave features #19

Open

nickreich merged commit 49d02f1 into main Dec 9, 2025
1 check passed

nickreich deleted the ngr/add-spatial-covariates branch December 9, 2025 15:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add directional wave features and release v1.1.0#15

Add directional wave features and release v1.1.0#15
nickreich merged 7 commits intomainfrom
ngr/add-spatial-covariates

nickreich commented Nov 17, 2025 •

edited

Loading

Uh oh!

Uh oh!

matthewcornell left a comment

Uh oh!

lshandross left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nickreich commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Features

Files Added

Files Modified

Data Source & Transparency

Test Results

Backwards Compatibility

Version

Documentation

Quick Start

Future Enhancements

Uh oh!

Uh oh!

matthewcornell left a comment

Choose a reason for hiding this comment

Uh oh!

lshandross left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nickreich commented Nov 17, 2025 •

edited

Loading